----------------------------------------------------------------------------- __ ___ ___ / \ |__ |__ \__/ | | An Informal Documentation Formatter ----------------------------------------------------------------------------- WRITER'S GUIDE Vassilis V. Dimakopoulos --- Last Revision: January 1993 --- QUICK OVERVIEW OFF will do certain things for your documents, like þ format your paragraphs þ center lines þ put attributes on the screen (e.g. bold, reverse, etc.) þ create lists of things Just write your document in any text editor without worrying for the visual beauty of it. You only have to put some simple keywords in some places that OFF will understand later to format your document. When finished just run OFF on your file and watch the result. Consult the OFF Reader's Guide for OFF' s options. STARTING Your document consists of paragraphs and commands. The commands affect the appearance of paragraphs. A paragraph is a set of contiguous lines that ends with a blank line. This means that a blank line starts a new paragraph. The job of OFF is basically to format the paragraphs by adding/deleting spaces so that all lines in a paragraph are both right and left indented by the same amount. An example follows: Document OFF output As I was walking down As I was walking down the road the road next next to my house I heard a to voice: my house I heard a voice: "You started a new paragraph "You started a new you stupid!" paragraph you stupid!" All the commands that OFF understands have the '%' character in front of them, e.g. '%center', '%macro'. Then the command name follows, without any space between the '%' and the command name. A space before or after a command is optional. If you want to actually print the character '%', precede it with a backslash (\). If want to print the backslash, precede it with another backslash (or else it will be ignored): Document OFF output Some characters: \%, \\, \\\% Some characters: %, \, \% In most of the cases you won't need to use (m)any commands. For example if you are writing a letter to somebody then probably you just want OFF to format your paragraphs (instead of doing it by hand!) and nothing else. In case you want to do fancy things (e.g. center some lines) then you probably need to know some of the commands OFF offers. Tutorial sections for the commands follow and the complete list is given for reference at the end of this document. ATTRIBUTES OFF has 4 commands to control the appearance of text when displayed or printed: %bold, %norm, %rev, %under. %bold makes text appear in bold style; %rev makes text appear reversed (black characters on white background or vice versa); %under produces underlined text; %norm resets everything to normal. NOTE: When OFF output is sent directly to a printer ( -p command line option,) then reversed characters actually appear as italics. Document OFF output Different attributes: Different attributes: %bold bold %rev reverse %under bold reverse underlined underlined LINE CONTROL COMMANDS You can tell OFF to treat a line of text in a special way, using the commands: %center, %right, %trio, %verb. %center will center a line; %right will flush a line towards the right end of the screen; %trio will produce a line consisting of 3 parts: a flushed-left, a centered and a flushed-right part; %verb will produce a line preserving all the spaces you typed (i.e. verbatim line, unlike lines inside paragraphs.) When OFF meets any of the above commands in your document, then it will read the rest of the line and process it accordingly. Document OFF output Look at the following three lines, Look at the following three lines that illustrate \%center, that illustrate %center, %right, \%right, \%trio and \%verb. %trio and %verb. %center Centered Centered %right Flushed right Flushed right %trio L %center C %right R L C R %verb Lots of spaces ! Lots of spaces ! As you can see in the last example, a %trio line should be typed as %trio %center
%right to create the 3-part line. You can omit any of the 3 parts if you wish. For example, %trio %right will produce a line with a left and a right part only. Some things should be noted about the %verb command: (a) it outputs spaces exactly as they appear in your document, even if these spaces are preceded by a command. For example, %verb a %bold b will produce --> a b while, %verb a%boldb will produce --> ab So watch your spaces! (b) keep in mind that the 1st space appearing after a %verb command is always ignored. (c) no indentation exists for verbatim lines, i.e. output begins at column 0 always. Inside a line that is to be formatted by the above commands, OFF only understands the %bold, %endcol, %newpage, %norm, %rev, %startcol, %under, %[ and %] commands. The last two commands do not make any sense inside a %verb line, of course. In the case you want to have many lines formatted by the above commands, instead of typing the command name in the beginning of each line, you can use the %begin command, as follows: %begin ... ... (lines to be processed) ... %end Do not forget the %end at the end! Document OFF output Here is a bunch of centered Here is a bunch of centered lines, using the \%begin center lines, using the %begin command: center command: %begin center First line First line Second line now Second line now The last line The last line %end You should keep in mind that whatever follows in the line of a '%begin ' or an '%end' is ignored. LISTS OFF can easily create lists of things, using the %list command. A list consists of items and each item consists of paragraphs. The items can be either numbered or marked with a symbol. The %list command may optionally be followed (immediately) by a number or a character. The rest of the line where '%list' lies is ignored. Rules: þ If nothing follows the %list command then the list is assumed to be a marked one and the symbol used for marking each item is the 'þ' character (like this list of rules!). þ If a character follows the %list command then the list will be a marked one but the symbol used for marking is the given character. þ If a number follows the %list command then the list will be a numbered list, the first item being numbered with the given number. Each item should start with the %item command. You can omit the %item command from the first item of the list, but if a list is a numbered one then numbers won't come out right: if N was normally the first number, the first item will be numbered with N-1. The list should finish with an %endlist command. Some examples follow: Document OFF output %list þ First item First item þ Second item %item Second item %endlist * First item * Second item %list * IGNORED! %item First item 5. First item %item Second item 6. Second item %endlist 7. Third item %list 5 (if there was not an %item below, we would start with 4) %item First item %item Second item %item Third item %endlist NOTES: OFF does not allow a list within a list. When the list is a numbered one then (a) OFF always puts a period after the number and (b) reserves 2 positions for the number, so the maximum number can be 99. PARAGRAPH CONTROL COMMANDS As shown in the introductory notes, when OFF reads a paragraph it treats newlines (or carriage returns) as spaces and does not start a new line at the output. If you want to force OFF to start a new line in a certain place in a paragraph use the (very useful) %nl command as shown in the following example. Document OFF output Here is a normal Here is a normal paragraph paragraph for OFF. for OFF. Here is a normal %nl Here is a normal paragraph for OFF. %nl (NOT !) paragraph for OFF. (NOT !) We also mentioned that (except for a %verb command) OFF ignores spaces when formatting. But there are some cases where you want a part of your text that includes many spaces to be output exactly as it is written. In this case the %[ %] command is for you ( is the text to be output as it is.) Document OFF output If %[ x = 2 %] is If x = 2 is true then true then we should ... we should ... The %[ ... %] command should not be confused with the %verb command, since they differ in two major issues: 1. %verb creates a line while %[ ... %] creates a word that can appear inside a paragraph. 2. Commands used inside a %[ ... %] have no effect (at least immediately). The %[ ... %] command can be used inside centered, flushed-right and trio lines as well. Now, a different issue. OFF normally indents the first line of a paragraph by 4 spaces (because it looks nicer). But maybe you want a certain paragraph not to be indented at all. In this case you can use the %noindent command: Document OFF output This is a nice paragraph This is a nice paragraph but i prefer the next one not but i prefer the next one to be indented. not to be indented. %noindent This paragraph looks This paragraph looks better better (I suppose.) (I suppose.) You should be careful that the %noindent command should be the first thing that appears in a new paragraph or else OFF will postpone the 'noindentation' for the next paragraph. Now, is may seem to you that every paragraph should be unindented, or that is should be indented by 30 spaces. OFF allows you to control the amount of paragraph indentation with the %parindent command. Use it as follows: %parindent where is the number of spaces you want your paragraph to be indented. If is zero, then indentation is removed from every paragraph in your document. In the latter case you may (highly unprobable) want to actually have a paragraph indented. You can then use the %indent command (exactly the way you used %noindent above) to have your paragraph indented by 4 spaces (cannot alter that). Actually, the %indent command may be useful if you want to indent the first paragraph of an item in a list (see the %list, %item commands). OFF normally does not indent the first paragraph of an item (because it looks better), so you can use %indent to override that. PAGE CONTROL COMMANDS You can control how pages are treated by OFF using the following commands: %pageno, %newpage, %startcol, %endcol. The 1st output page is page number 1 and this number increases by 1 with every new displayed page. To change the page number to whatever you want, use the %pageno command as follows: %pageno where is the desired number. should be >= zero and <= 999. Note that the page number does not appear anywhere in OFF' s output unless the header and/or the footer of a page ask for it (see the next section). Be careful that a change in the page number actually affects only the footer of the current page, not its header. The effect on the header takes place on the next page, so be careful where you want your page numbers to appear... The %newpage command makes OFF fill the rest of a page with blank lines and start a new page at the output. Be careful that if this command lies inside a paragraph, the page break will NOT occur after the word preceding the %newpage command. OFF will finish formatting the previous line (which may or may not include the preceding word(s)) and then start a new line (which probably contains some of the preceding words) in the new page. So, usually, a %newpage command lies after the end of a paragraph. OFF thinks that it can output text in a screen that has a width of 80 characters. Also, OFF believes that you want your formatted document to appear between (and including) columns 5 and 75 . Remember that columns are numbered from 0 to 79. You can change these numbers so that your document is more wide or more narrow, with the self-explaining commands %startcol and %endcol. These commands should be followed by the desired number. A word of advice: experiments with very narrow pages were proven a disaster. A page less than about 15 characters wide cause OFF to terminate unexpectedly. %startcol cannot be less than zero and %endcol cannot be more than 79. Also, OFF tries to make sure that %endcol - %startcol is at least 5 so that it can display at least 5 characters per line. Keep also in mind that the page length is assumed to be 24 lines whenever the output is displayed on a screen and 66 lines whenever it is directed to a printer or an ascii file. You cannot change these numbers inside your document; the same holds for the page width; you can do that only when you run OFF with the -l and -w options -- see the OFF Reader's Guide HEADERS & FOOTERS Normally OFF outputs plain pages. In some cases though (like in this document) it is useful to have a line that appears at the top (a header) and/or a line that appears at the bottom (a footer) of every page. OFF has two commands that allow you to define a header and a footer: the %header and %footer commands. Actually these commands work exactly like the %trio command (which see.) Hence, for example, the footer of this document was defined as: %footer V. Dimakopoulos %right %[O F F %] Writer's Manual Whatever commands are allowed inside a %trio line are allowed for the header and footer lines too. The only addition is the %pn command which produces the current page number in the document. For example, the header of this page was defined as: %header Headers & Footers %right Page %pn Note that %pn is allowed only in footers and headers and nowhere else. The page number is controlled by the %pageno command as explained in a previous section. Two important things should be noted: 1. The very first page of the paragraph never has a header (it's a long story..) If you want it to be like the other pages, make a 'header' by yourself using the %center, %right, %trio or %verb commands. A footer, though, may exist in the first page. 2. The header is displayed first, then text is read and displayed and lastly the footer is displayed. If inside the text you change the page number with a %pageno command, only the footer will be affected. Hence if the page number appears in both the header and the footer, there will be a mismatch. Things of course will settle in the next page. The following commands tell OFF whether to actually output the header/footer or not: %hshow %fshow If is 0 then starting from the current page, OFF will stop outputting the header (if %hshow is 0) and/or the footer (if %fshow is 0). Any positive will turn the header/footer output on. Now, since OFF by default outputs plain pages (even if there are headers/footers defined,) after defining your header/footer you have to explicitly turn output on. The final commands that control headers/footers are %hspace and %fspace. Normally, OFF leaves 2 blank lines between the header and the text of a page. Use %hspace to set this distance to lines. In the same way, you can use %fspace to set the distance between the text and the footer to lines. The default for OFF is again 2 lines. MACROS Macros are useful when a series of commands or words need to be used repeatedly throughout the document. This way one can save precious typing time plus avoid mistakes. Each macro has a unique name. You have to define a macro first and then call it every time you need it. To define a macro start with a '%defmacro ' command, where is the name this macro will have. After entering the text, give an '%endmacro' command to finish your definition. Now, each time you want to call this macro you have to issue a '%mname' command, i.e. like there was a command named 'mname'. If a macro is named after one of the standard commands of OFF then your macro will never be called! Calling the macro is equivalent to re-writing the text inside the definition of the macro. An example follows. Document OFF output %defmacro rc We are going to present %bold RECIPEE-CAD %norm RECIPEE-CAD now. RECIPEE-CAD %endmacro is a revolutionary cooking aid. Unlike ordinary recipe We are going to present books, RECIPEE-CAD ... %rc now. %rc is a revolutionary cooking aid. Unlike ordinary recipe books, %rc ... It should be mentioned that everything that follows a '%defmacro ' and an '%endmacro' (in the same line) is ignored. OFF allows up to 10 macros inside a document. The name of each macro should be at most 10 characters long. Finally, each macro definition should not exceed 1000 characters. OFF COMMANDS LIST INDEX COMMAND MEANING (2) %begin - apply a command to many lines (1) %bold - start bold output (2) %center - center a line (7) %defmacro - define a macro named (2) %end - end a %begin command (5) %endcol - set last column of output (3) %endlist - end a list (7) %endmacro - end a macro definition (6) %footer - define the page footer (6) %fshow - display on/off of the footer (6) %fspace - set distance of footer from text (6) %header - define the page header (6) %hshow - display on/off of the header (6) %hspace - set distance of header from text (4) %indent - indent a paragraph not meant to be indented (3) %item - start an item in a list (3) %list - start a list (7) %macro - call the macro named (5) %newpage - start a new page (4) %nl - start a new line immediately (4) %noindent - the opposite of %indent (1) %norm - start normal output (4) %parindent - set global paragraph indentation width (5) %pageno - set the page number (6) %pn - show page number in footer/header (1) %rev - start reverse output (2) %right - flush right a line (5) %startcol - set first column of output (2) %trio - create a 3-part line (1) %under - start underlined output (2) %verb - a verbatim line follows (4) %[%] - produce a verbatim word Indices: (1) - Attributes (2) - Line Control Commands (3) - Lists (4) - Paragraph Control Commands (5) - Page Control Commands (6) - Headers & Footers (7) - Macros